home *** CD-ROM | disk | FTP | other *** search
/ IRIX Base Documentation 2002 November / SGI IRIX Base Documentation 2002 November.iso / usr / share / catman / p_man / cat3s / flockfile.z / flockfile
Encoding:
Text File  |  2002-10-03  |  7.9 KB  |  133 lines
  1.  
  2.  
  3.  
  4. fffflllloooocccckkkkffffiiiilllleeee((((3333SSSS))))                                                    fffflllloooocccckkkkffffiiiilllleeee((((3333SSSS))))
  5.  
  6.  
  7.  
  8. NNNNAAAAMMMMEEEE
  9.      _ffff_llll_oooo_cccc_kkkk_ffff_iiii_llll_eeee, _ffff_tttt_rrrr_yyyy_llll_oooo_cccc_kkkk_ffff_iiii_llll_eeee, _ffff_uuuu_nnnn_llll_oooo_cccc_kkkk_ffff_iiii_llll_eeee - stdio synchronization functions
  10.  
  11. SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS
  12.      _####_iiii_nnnn_cccc_llll_uuuu_dddd_eeee _<<<<_ssss_tttt_dddd_iiii_oooo_...._hhhh_>>>>
  13.  
  14.      _vvvv_oooo_iiii_dddd _ffff_llll_oooo_cccc_kkkk_ffff_iiii_llll_eeee _((((_FFFF_IIII_LLLL_EEEE _****_ffff_iiii_llll_eeee_))))_;;;;
  15.  
  16.      _iiii_nnnn_tttt _ffff_tttt_rrrr_yyyy_llll_oooo_cccc_kkkk_ffff_iiii_llll_eeee _((((_FFFF_IIII_LLLL_EEEE _****_ffff_iiii_llll_eeee_))))_;;;;
  17.  
  18.      _vvvv_oooo_iiii_dddd _ffff_uuuu_nnnn_llll_oooo_cccc_kkkk_ffff_iiii_llll_eeee _((((_FFFF_IIII_LLLL_EEEE _****_ffff_iiii_llll_eeee_))))_;;;;
  19.  
  20. DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
  21.      _ffff_llll_oooo_cccc_kkkk_ffff_iiii_llll_eeee, _ffff_tttt_rrrr_yyyy_llll_oooo_cccc_kkkk_ffff_iiii_llll_eeee, and _ffff_uuuu_nnnn_llll_oooo_cccc_kkkk_ffff_iiii_llll_eeee provide for explicit locking and
  22.      unlocking of stdio streams.  They may be used by a thread to delineate a
  23.      sequence of I/O statements to be executed as a critical section.
  24.  
  25.      _ffff_llll_oooo_cccc_kkkk_ffff_iiii_llll_eeee is used by a thread to acquire exclusive use of _f_i_l_e.
  26.  
  27.      _ffff_tttt_rrrr_yyyy_llll_oooo_cccc_kkkk_ffff_iiii_llll_eeee is used by a thread to acquire exclusive use of _f_i_l_e if it
  28.      is available; _ffff_tttt_rrrr_yyyy_llll_oooo_cccc_kkkk_ffff_iiii_llll_eeee is a nonblocking version of _ffff_llll_oooo_cccc_kkkk_ffff_iiii_llll_eeee.
  29.      _ffff_tttt_rrrr_yyyy_llll_oooo_cccc_kkkk_ffff_iiii_llll_eeee returns zero if it successfully acquires the lock, otherwise
  30.      a nonzero value is returned.
  31.  
  32.      _ffff_uuuu_nnnn_llll_oooo_cccc_kkkk_ffff_iiii_llll_eeee is used to give up the exclusive control granted to the
  33.      thread.
  34.  
  35.      Logically, there is a lock count associated with _f_i_l_e.  The count is
  36.      implicitly initialized to 0 when the _f_i_l_e is opened.  _f_i_l_e is unlocked
  37.      when the count is 0.  When the count is positive a single thread holds
  38.      the lock.  Each call to _ffff_llll_oooo_cccc_kkkk_ffff_iiii_llll_eeee (or successful call to _ffff_tttt_rrrr_yyyy_llll_oooo_cccc_kkkk_ffff_iiii_llll_eeee)
  39.      increments the lock count while each call to _ffff_uuuu_nnnn_llll_oooo_cccc_kkkk_ffff_iiii_llll_eeee decrements the
  40.      lock count.  When the lock count is non-zero, threads not holding the
  41.      lock on _f_i_l_e that call _ffff_llll_oooo_cccc_kkkk_ffff_iiii_llll_eeee will suspend and wait for the count to
  42.      return to 0.  The thread holding the lock on _f_i_l_e does not suspend itself
  43.      on multiple calls to _ffff_llll_oooo_cccc_kkkk_ffff_iiii_llll_eeee, allowing for the nesting of matching
  44.      calls to _ffff_llll_oooo_cccc_kkkk_ffff_iiii_llll_eeee (or successful calls to _ffff_tttt_rrrr_yyyy_llll_oooo_cccc_kkkk_ffff_iiii_llll_eeee) and _ffff_uuuu_nnnn_llll_oooo_cccc_kkkk_ffff_iiii_llll_eeee.
  45.  
  46.      All functions in stdio use these functions to guarantee reentrancy.  All
  47.      reentrant macros behave as if they are surrounded by calls to _ffff_llll_oooo_cccc_kkkk_ffff_iiii_llll_eeee
  48.      and _ffff_uuuu_nnnn_llll_oooo_cccc_kkkk_ffff_iiii_llll_eeee.
  49.  
  50.      The feature test macro ______SSSS_GGGG_IIII______RRRR_EEEE_EEEE_NNNN_TTTT_RRRR_AAAA_NNNN_TTTT______FFFF_UUUU_NNNN_CCCC_TTTT_IIII_OOOO_NNNN_SSSS should be defined to make
  51.      these functions visible.
  52.  
  53.      The semantics of _ffff_llll_oooo_cccc_kkkk_ffff_iiii_llll_eeee, _ffff_tttt_rrrr_yyyy_llll_oooo_cccc_kkkk_ffff_iiii_llll_eeee, and _ffff_uuuu_nnnn_llll_oooo_cccc_kkkk_ffff_iiii_llll_eeee are undefined
  54.      if _f_i_l_e is not a valid (_F_I_L_E *) object.  Calling _ffff_uuuu_nnnn_llll_oooo_cccc_kkkk_ffff_iiii_llll_eeee without
  55.      previously calling _ffff_llll_oooo_cccc_kkkk_ffff_iiii_llll_eeee (or successfully calling _ffff_tttt_rrrr_yyyy_llll_oooo_cccc_kkkk_ffff_iiii_llll_eeee)
  56.      results in indeterminate behavior.
  57.  
  58.  
  59.  
  60.  
  61.  
  62.  
  63.                                                                         PPPPaaaaggggeeee 1111
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70. fffflllloooocccckkkkffffiiiilllleeee((((3333SSSS))))                                                    fffflllloooocccckkkkffffiiiilllleeee((((3333SSSS))))
  71.  
  72.  
  73.  
  74. EEEEXXXXAAAAMMMMPPPPLLLLEEEE
  75.      Here is a code fragment that uses these functions to guarantee that the
  76.      output will be printed without being interspersed with output from other
  77.      threads.
  78.  
  79.           _####_iiii_nnnn_cccc_llll_uuuu_dddd_eeee _<<<<_ssss_tttt_dddd_iiii_oooo_...._hhhh_>>>>
  80.  
  81.                _ffff_llll_oooo_cccc_kkkk_ffff_iiii_llll_eeee_((((_ssss_tttt_dddd_oooo_uuuu_tttt_))))_;;;;
  82.                _pppp_uuuu_tttt_cccc_hhhh_aaaa_rrrr______uuuu_nnnn_llll_oooo_cccc_kkkk_eeee_dddd_((((_''''_1111_''''_))))_;;;;
  83.                _pppp_uuuu_tttt_cccc_hhhh_aaaa_rrrr______uuuu_nnnn_llll_oooo_cccc_kkkk_eeee_dddd_((((_''''_\\\\_nnnn_''''_))))_;;;;
  84.                _pppp_rrrr_iiii_nnnn_tttt_ffff_((((_""""_LLLL_iiii_nnnn_eeee _2222_\\\\_nnnn_""""_))))_;;;;
  85.                _ffff_uuuu_nnnn_llll_oooo_cccc_kkkk_ffff_iiii_llll_eeee_((((_ssss_tttt_dddd_oooo_uuuu_tttt_))))_;;;;
  86.  
  87. SSSSEEEEEEEE AAAALLLLSSSSOOOO
  88.      _iiii_nnnn_tttt_rrrr_oooo(3), _gggg_eeee_tttt_cccc(3S) _pppp_uuuu_tttt_cccc(3S) _ssss_tttt_dddd_iiii_oooo(3S).
  89.  
  90.  
  91.  
  92.  
  93.  
  94.  
  95.  
  96.  
  97.  
  98.  
  99.  
  100.  
  101.  
  102.  
  103.  
  104.  
  105.  
  106.  
  107.  
  108.  
  109.  
  110.  
  111.  
  112.  
  113.  
  114.  
  115.  
  116.  
  117.  
  118.  
  119.  
  120.  
  121.  
  122.  
  123.  
  124.  
  125.  
  126.  
  127.  
  128.  
  129.                                                                         PPPPaaaaggggeeee 2222
  130.  
  131.  
  132.  
  133.